Libris Britannia 4/science library(b).zip/science library(b)/COMMUNIC/BULLETIN/0157.ZIP/GENERIC.DOC

Text File | 1985-11-14 | 9KB | 249 lines

    GENERIC FIDO DRIVER INTERFACE
    T. Jennings 12 July 1985

    FIDO_GEN.EXE is a "generic" Fido for otherwise unsupported
    machines. It will not work until you write a device driver
    or terminate-stay-resident program to provide the following
    functions. The format of this driver will remain independent
    of the Fido version; once written it will work with all
    future Fido versions.

    All IO is done through an IBM PC like Interrupt 14 hex. Many
    calls are directly compatible, but you will have to extend
    it to support the added features. Note that FIDO_GEN will
    NOT run on an IBM PC as is.

    The interface is very consistent; AX and DX are used for
    all functions.

    It is possible to use an entirely polled IO system for
    Fido; Fido does "typeahead" in the higher level software,
    so everything but ASCII Upload will work fine polled, and
    even that may work OK on most machines. Interrupt character
    input is very desireable. Interrupt output is not needed
    at all, unless you wish to run under a multi-tasker such
    as Multilink.

    Please note that I cannot help you write drivers, nor will
    I help you debug them. You are on your own! Extensive
    assembly language experience is needed, and a good degree
    of familiarity with your hardware, so please do not
    underestimate the difficulty of this task.

    Assumptions here are that you can run MSDOS or PCDOS
    version 2 or 3; Fido does not support ANY other operating
    system.

    Either a device driver or a terminate-stay-resident type
    structure for your driver set is reccomended. Device drivers
    obviously go in your CONFIG.SYS on the boot disk; term stay
    res programs should be put in AUTOEXEC.BAT, to be run only
    ONCE. Every time you run a term stay res, it consumes more
    memory, unless special provision is made in your program
    to detect whether it was previously loaded. Keep in mind that
    in normal operation, Fido is run more than once, ie. you may
    Control-C Fido to copy files, run in Test Mode, etc.

    On the subject of Test Mode, an important note: Fido does not
    make ANY HARDWARE DEPENDENT CALLS in /T test mode. This means
    that ANY version of Fido will work on ANY other machine in
    test mode. You must run it without /T specified in order to
    get it to use your drivers. Test mode is useless as a test of
    your drivers. It means nothing.

    It is probably a good idea to test each and every single
    function before attempting to use Fido with your driver set;
    I repeat, I cannot help you with your drivers in any way.


    The following is the function call used internally to Fido
    to access the drivers you write. This is provided for your
    information only.

    val= int14(ah,al,dx);

    int val;        /* integer return value */

    int ah;            /* command byte, 0 - N */
    int al;            /* argument */
    int dx;            /* I/O device, ie. channel */


    For all calls, DX is the IO device from the /1, /2, etc
    command line switch. This can be used or ignored as desired.
    It will be valid for all calls at all times.

    AH is the command type; 0 - 3 are very similar to IBM PC
    INT 14 calls. 4 and up are extentions to support further
    functions. (Note that the IBM version of Fido does NOT
    use INT 14.)

    For all calls, your driver MUST preserve all segment
    registers, plus BP and SP. All other registers can be
    modified. Interrupts should be left ENABLED after
    returning. There is adequate stack space to do almost
    anything you need; there should be at least a kilobyte
    of stack space.


AH = 0:    Set baud rate

    This command is almost identical to the IBM PC equivalent
    call. The upper three bits indicate the baud rate; the
    lower ones indicate parity (always none) and stop bits
    (always 1). You can always assume that NO PARITY and ONE
    STOP BIT are used throughout Fido.

        Baud    Value
         300    043h
        1200    083h
        2400    0a3h
        9600    0e3h

    The sample driver strips off all but the upper three
    bits. You can do this in your driver also, but Fido
    will always pass the byte patterns as defined above.



AH = 1:    Write a character to the serial port

    Output the character in AL to the serial port. Wait for
    output ready as necessary.



AH = 2:    Read a character from the serial port

    Return one character from the serial port in AL. Wait for
    one if necessary.


AH = 3:    Return status

    This command returns various status bits back to Fido in AH
    and AL. There are three status bits you must return in this
    call; two have predetermined values, and the other you can
    assign to any other bit, as it is tested with the command
    line /V value. (See below) These are bit patterns, not
    numeric values; you can (and will) have more than one bit
    set at a time.

    AH:    20h        TBE    Transmit Buffer Empty
        01h        RDA    Receive Data Available

    TBE means the transmitter is ready to accept a character.
    RDA means there is a character from the modem waiting.

    The other bit the the Carrier Detect (CD) bit. This can be
    returned in either AH or AL. The command line switch /V
    defines the mask bit used to test this port. For example,

        128/V

    Defines the CD mask bit to be 128, or 0080h. This is ANDed
    with the value returned by the STATUS call, and if the
    result is true (bit is set) then Fido assumes the modem is
    connected.

    For making this test, Fido treats AH and AL as a 16 bit
    integer, in the usual fashion: AH is the most signifigant
    and AL the least.  Therefore, 32768/V tests the MSB in
    AH, and 1/V test the LSB in AL. You can't use 8192/V
    or 256/V, since those are TBE and RDA, respectively.

    Unused bits may take on any value as you see fit.



AH = 4:    One time initialization

    Perform any necessary one time initialization here. Fido
    will make this call only ONCE before any IO is done to
    the serial port. NO OTHER call will ever be made before
    this call. If not needed, ignore.


AH = 5:    One time UN initialization

    Do one time un-initialization; this is called ONCE, just
    before Fido exits to DOS. Remove any interrupt structures
    or whatever were installed by AH = 0. NO OTHER call will be
    mode to the IO drivers after this call.

    It is general practice when exiting Fido to leave the
    DTR line low so that the modem is disabled when Fido
    is not running. Fido lowers DTR before calling this
    function and exiting, but you might want to make sure that
    this function does not raise it again inadvertantly.



AH = 6:    Raise/Lower Data Terminal Ready

    This function controls the state of the DTR line output to
    the modem, usually on Pin 20. AL = 0 means lower DTR;
    AL = 1 means raise it true. True enables the modem; false
    disables it.

    No other functions in your drivers should change the state
    of the DTR line, except AH = 4 and AH = 5. See the note
    in AH = 5 about exiting Fido.

AH = 7:    Return Timer Tick parameters

    This function is used to tell Fido about the timer tick
    to be used for marking time. This is an extremely critical
    function, and luckily, fairly simple. The hard part will
    be getting the information.

    AH = 4 is called before this call, so you can use that to
    start any timer running if necessary; if you do, use AH = 5
    to remove it.

    AH = 7 returns three numbers:

        AL =     Timer Tick Interrupt Number    0 - 255
        AH =    Ticks Per Second
        DX =     Timer Tick Rate, Milliseconds

    Note that this function merely returns fixed values to
    Fido; Fido will do all the work of operating the timer
    interrupt, and pass control to the original interrupt
    service routine. The following information is given
    as background only.

    Fido's timer tick is done very simply by inserting itself
    in series with the interrupt numbe you specify in AL. When
    Fido has done its timer counter incrementing, it chains
    via a long jump to the original interrupt vector, thereby
    preserving the original interrupt vector. Fido does not
    defer the interrupt by more than a few hundred microseconds,
    so there are no problems with interrupt acknowledges
    regardless of the interrupt system type. The DEC Rainbow,
    for instance, has a low tolerance for interrupt deferrment;
    it has hardware to check for interrupt loss, and the screen
    refresh depends on a repeatable clock; Fido's timer tick
    method presents no problem.

    The reason for both ticks per second and milliseconds per
    tick is that frequently the timer is at an inconvenient rate;
    the IBM PC for example is approx. 55 mS, which does not make
    for easy counting. (Note that if you work it out, the
    sample drive as supplied is very inaccurate. Oh well.)

    Fido counts both milliseconds and hours minutes seconds; these
    two parameters let you choose values that will result in the
    highest accuracy. It is not necessary to have extreme accuracy.

    Fido does its millisecond counting by adding the number you
    return in DX to a 32 bit counter in memory; it is used for
    XMODEM, etc timeouts, and does not need to be highly accurate;
    10% is fine, but try for the most accurate possible.

    Hour minute second counting is done with the number your return
    in AH; every (AH) timer tick Fido increments the seconds counter.
    This value should be as accurate as is possible, since this is
    what controls each users time limit on the system.